
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
    <link href='/css/styles.css' rel='stylesheet' type='text/css' />
    <link href='/images/favicon.png' rel='shortcut icon' />
    <script src='/js/jquery.min.1.4.js'></script>
    <script src='/js/app.js'></script>
    <script src='/js/common.js'></script>
    
    <meta content='width=device-width, minimum-scale=1.0, maximum-scale=1.0' name='viewport' />
    <title>redis - 命令</title>
	<meta http-equiv="description" content="redis中文资料站，下载安装redis，查找redis常用命令（commands），选择适合的redis客户端方式，配置redis主从（master-slave），阅读redis官方文档，社区里了解更多redis信息，提交redis的bug。" />
	
  </head>
  <body class=''>
    <script src='/js/head.js'></script>
    <div class='text'>
      <h1 class='command'>
        <span id='command_name_span' class='name'></span>
        <span id='command_args_span' class='arg'></span>
      </h1>
      <article>
       	<aside>
        	<script type='text/javascript'>showCmdURL();</script>
        </aside>
        <div class='metadata'>
          <p><strong>加入版本 <span id='command_ver_span'></span>。</strong></p>
          <p><strong>时间复杂度：</strong>增量式迭代命令每次执行的复杂度为O(1) ,对数据集进行一次完整迭代的复杂度为O(N) ,其中 N 为数据集中的元素数量。</p>
        </div>
        
      	<p>The <a href="/commands/scan.html">SCAN</a> 命令及其相关的 <a href="/commands/sscan.html">SSCAN</a>, <a href="/commands/hscan.html">HSCAN</a> and <a href="/commands/zscan.html">ZSCAN</a> 命令都用于增量迭代一个集合元素。</p>
        
        <ul>
        <li><a href="/commands/scan.html">SCAN</a> 命令用于迭代当前数据库中的key集合。</li>
        <li><a href="/commands/sscan.html">SSCAN</a> 命令用于迭代SET集合中的元素。</li>
        <li><a href="/commands/hscan.html">HSCAN</a> 命令用于迭代Hash类型中的键值对。</li>
        <li><a href="/commands/zscan.html">ZSCAN</a> 命令用于迭代SortSet集合中的元素和元素对应的分值</li>
        </ul>
        
        <p>以上列出的四个命令都支持增量式迭代，它们每次执行都只会返回少量元素，所以这些命令可以用于生产环境，而不会出现像 <a href="/commands/keys">KEYS</a> or <a href="/commands/smembers">SMEMBERS</a> 命令带来的可能会阻塞服务器的问题。</p>
        
        <p>不过，<a href="/commands/smembers.html">SMEMBERS</a> 命令可以返回集合键当前包含的所有元素， 但是对于<a href="/commands/scan.html">SCAN</a>这类增量式迭代命令来说，有可能在增量迭代过程中，集合元素被修改，对返回值无法提供完全准确的保证。</p>
        
        <p>因为 <a href="/commands/scan.html">SCAN</a>, <a href="/commands/sscan.html">SSCAN</a>, <a href="/commands/hscan.html">HSCAN</a> and <a href="/commands/zscan.html">ZSCAN</a> 四个命令的工作方式都非常相似， 所以这个文档会一并介绍这四个命令，需要注意的是<a href="/commands/sscan.html">SSCAN</a>, <a href="/commands/hscan.html">HSCAN</a> ,<a href="/commands/zscan.html">ZSCAN</a>命令的第一个参数总是一个key； <a href="/commands/scan.html">SCAN</a> 命令则不需要在第一个参数提供任何key，因为它迭代的是当前数据库中的所有key。</p>
        
        <h2>SCAN命令的基本用法</h2>
        
        <p>SCAN 命令是一个基于游标的迭代器。这意味着命令每次被调用都需要使用上一次这个调用返回的游标作为该次调用的游标参数，以此来延续之前的迭代过程</p>
        
        <p>当 SCAN 命令的游标参数被设置为 0 时， 服务器将开始一次新的迭代， 而当服务器向用户返回值为 0 的游标时， 表示迭代已结束。</p>
        
		<p>以下是一个 SCAN 命令的迭代过程示例 :</p>
        <pre><code>redis 127.0.0.1:6379&gt; scan 0&#x000A;1) &quot;17&quot;&#x000A;2)  1) &quot;key:12&quot;&#x000A;    2) &quot;key:8&quot;&#x000A;    3) &quot;key:4&quot;&#x000A;    4) &quot;key:14&quot;&#x000A;    5) &quot;key:16&quot;&#x000A;    6) &quot;key:17&quot;&#x000A;    7) &quot;key:15&quot;&#x000A;    8) &quot;key:10&quot;&#x000A;    9) &quot;key:3&quot;&#x000A;   10) &quot;key:7&quot;&#x000A;   11) &quot;key:1&quot;&#x000A;redis 127.0.0.1:6379&gt; scan 17&#x000A;1) &quot;0&quot;&#x000A;2) 1) &quot;key:5&quot;&#x000A;   2) &quot;key:18&quot;&#x000A;   3) &quot;key:0&quot;&#x000A;   4) &quot;key:2&quot;&#x000A;   5) &quot;key:19&quot;&#x000A;   6) &quot;key:13&quot;&#x000A;   7) &quot;key:6&quot;&#x000A;   8) &quot;key:9&quot;&#x000A;   9) &quot;key:11&quot;&#x000A;</code></pre>
        
        <p>在上面这个例子中， 第一次迭代使用 0 作为游标， 表示开始一次新的迭代。第二次迭代使用的是第一次迭代时返回的游标 17 ，作为新的迭代参数 。</p>
        
        <p>显而易见，<strong>SCAN命令的返回值</strong> 是一个包含两个元素的数组， 第一个数组元素是用于进行下一次迭代的新游标， 而第二个数组元素则是一个数组， 这个数组中包含了所有被迭代的元素。</p>
        
        <p>在第二次调用 SCAN 命令时， 命令返回了游标 0 ， 这表示迭代已经结束， 整个数据集已经被完整遍历过了。</p>
	    
		<p> <strong>full iteration ：</strong>以 0 作为游标开始一次新的迭代， 一直调用 SCAN 命令， 直到命令返回游标 0 ， 我们称这个过程为一次完整遍历。</p>
        
        <h2>Scan命令的保证</h2>
        
        <p><a href="/commands/scan.html">SCAN</a>命令以及其他增量式迭代命令， 在进行完整遍历的情况下可以为用户带来以下保证 ：</p>
        
        <ul>
        <li>从完整遍历开始直到完整遍历结束期间， 一直存在于数据集内的所有元素都会被完整遍历返回； 这意味着， 如果有一个元素， 它从遍历开始直到遍历结束期间都存在于被遍历的数据集当中， 那么 SCAN 命令总会在某次迭代中将这个元素返回给用户。</li>
        <li>同样，如果一个元素在开始遍历之前被移出集合，并且在遍历开始直到遍历结束期间都没有再加入，那么在遍历返回的元素集中就不会出现该元素。</li>
        </ul>
        
        <p>然而因为增量式命令仅仅使用游标来记录迭代状态， 所以这些命令带有以下缺点：</p>
        
        <ul>
        <li>同一个元素可能会被返回多次。 处理重复元素的工作交由应用程序负责， 比如说， 可以考虑将迭代返回的元素仅仅用于可以安全地重复执行多次的操作上。</li>
        <li>如果一个元素是在迭代过程中被添加到数据集的， 又或者是在迭代过程中从数据集中被删除的， 那么这个元素可能会被返回， 也可能不会。</li>
        </ul>
        
        <h2>SCAN命令每次执行返回的元素数量</h2>
        
        <p><a href="/commands/scan.html">SCAN</a>增量式迭代命令并不保证每次执行都返回某个给定数量的元素,甚至可能会返回零个元素， 但只要命令返回的游标不是 0 ， 应用程序就不应该将迭代视作结束。</p>
        
        <p>不过命令返回的元素数量总是符合一定规则的， 对于一个大数据集来说， 增量式迭代命令每次最多可能会返回数十个元素；而对于一个足够小的数据集来说， 如果这个数据集的底层表示为编码数据结构（小的sets, hashes and sorted sets）， 那么增量迭代命令将在一次调用中返回数据集中的所有元素。</p>
        
        <p>如果需要的话，用户可以通过增量式迭代命令提供的  <strong>COUNT</strong>选项来指定每次迭代返回元素的最大值。</p>
        
        <h2>COUNT选项</h2>
        
        <p>对于增量式迭代命令不保证每次迭代所返回的元素数量，我们可以使用<strong>COUNT</strong>选项， 对命令的行为进行一定程度上的调整。COUNT 选项的作用就是让用户告知迭代命令， 在每次迭代中应该<em>从数据集里返回多少元素</em>。使用COUNT 选项对于对增量式迭代命令相当于一种<strong>提示</strong>， 大多数情况下这种提示都比较有效的控制了返回值的数量。</p>
        
        <ul>
        <li>COUNT 参数的默认值为 10 。</li>
        <li>数据集比较大时，如果没有使用<strong>MATCH</strong> 选项, 那么命令返回的元素数量通常和 COUNT 选项指定的一样， 或者比 COUNT 选项指定的数量稍多一些。</li>
        <li>在迭代一个编码为整数集合（intset，一个只由整数值构成的小集合）、 或者编码为压缩列表（ziplist，由不同值构成的一个小哈希或者一个小有序集合）时， 增量式迭代命令通常会无视 COUNT 选项指定的值， 在第一次迭代就将数据集包含的所有元素都返回给用户。</li>
        </ul>
        
        <p>注意: <strong>并非每次迭代都要使用相同的 COUNT 值</strong> ，用户可以在每次迭代中按自己的需要随意改变 COUNT 值， 只要记得将上次迭代返回的游标用到下次迭代里面就可以了。</p>
        
        <h2>MATCH 选项</h2>
        
        <p>类似于<a href="/commands/keys.html">KEYS</a> 命令，增量式迭代命令通过给定 MATCH <pattern> 参数的方式实现了通过提供一个 glob 风格的模式参数， 让命令只返回和给定模式相匹配的元素。 </p>
        
        <p>以下是一个使用 <strong>MATCH</strong> 选项进行迭代的示例:</p>
        
        <pre><code>redis 127.0.0.1:6379&gt; sadd myset 1 2 3 foo foobar feelsgood&#x000A;(integer) 6&#x000A;redis 127.0.0.1:6379&gt; sscan myset 0 match f*&#x000A;1) &quot;0&quot;&#x000A;2) 1) &quot;foo&quot;&#x000A;   2) &quot;feelsgood&quot;&#x000A;   3) &quot;foobar&quot;&#x000A;redis 127.0.0.1:6379&gt;&#x000A;</code></pre>
        
		<p><strong>MATCH</strong>功能对元素的模式匹配工作是在命令从数据集中取出元素后和向客户端返回元素前的这段时间内进行的， 所以如果被迭代的数据集中只有少量元素和模式相匹配， 那么迭代命令或许会在多次执行中都不返回任何元素。</p>
		
		<p> 以下是这种情况的一个例子:</p>
        
        <pre><code>redis 127.0.0.1:6379&gt; scan 0 MATCH *11*&#x000A;1) &quot;288&quot;&#x000A;2) 1) &quot;key:911&quot;&#x000A;redis 127.0.0.1:6379&gt; scan 288 MATCH *11*&#x000A;1) &quot;224&quot;&#x000A;2) (empty list or set)&#x000A;redis 127.0.0.1:6379&gt; scan 224 MATCH *11*&#x000A;1) &quot;80&quot;&#x000A;2) (empty list or set)&#x000A;redis 127.0.0.1:6379&gt; scan 80 MATCH *11*&#x000A;1) &quot;176&quot;&#x000A;2) (empty list or set)&#x000A;redis 127.0.0.1:6379&gt; scan 176 MATCH *11* COUNT 1000&#x000A;1) &quot;0&quot;&#x000A;2)  1) &quot;key:611&quot;&#x000A;    2) &quot;key:711&quot;&#x000A;    3) &quot;key:118&quot;&#x000A;    4) &quot;key:117&quot;&#x000A;    5) &quot;key:311&quot;&#x000A;    6) &quot;key:112&quot;&#x000A;    7) &quot;key:111&quot;&#x000A;    8) &quot;key:110&quot;&#x000A;    9) &quot;key:113&quot;&#x000A;   10) &quot;key:211&quot;&#x000A;   11) &quot;key:411&quot;&#x000A;   12) &quot;key:115&quot;&#x000A;   13) &quot;key:116&quot;&#x000A;   14) &quot;key:114&quot;&#x000A;   15) &quot;key:119&quot;&#x000A;   16) &quot;key:811&quot;&#x000A;   17) &quot;key:511&quot;&#x000A;   18) &quot;key:11&quot;&#x000A;redis 127.0.0.1:6379&gt;&#x000A;</code></pre>
        
        <p>可以看出，以上的大部分迭代都不返回任何元素。在最后一次迭代， 我们通过将 COUNT 选项的参数设置为 1000 ， 强制命令为本次迭代扫描更多元素， 从而使得命令返回的元素也变多了。</p>
        
        <h2>并发执行多个迭代</h2>
        
        <p>在同一时间， 可以有任意多个客户端对同一数据集进行迭代， 客户端每次执行迭代都需要传入一个游标， 并在迭代执行之后获得一个新的游标， 而这个游标就包含了迭代的所有状态， 因此， 服务器无须为迭代记录任何状态。</p>
        
        <h2>中止迭代</h2>
        
        <p>因为迭代的所有状态都保存在游标里面， 而服务器无须为迭代保存任何状态， 所以客户端可以在中途停止一个迭代， 而无须对服务器进行任何通知。即使有任意数量的迭代在中途停止， 也不会产生任何问题。</p>
        
        <h2>使用错误的游标</h2>
        
        <p>使用<a href="/commands/scan.html">SCAN</a> 命令传入间断的（broken）、负数、超出范围或者其他非正常的游标来执行增量式迭代并不会造成服务器崩溃， 但可能会让命令产生未定义的行为。未定义行为指的是， 增量式命令对返回值所做的保证可能会不再为真。</p>
        
        <p>只有两种游标是合法的:</p>
        
        <ul>
        <li>在开始一个新的迭代时， 游标必须为 0 。</li>
        <li>增量式迭代命令在执行之后返回的， 用于延续迭代过程的游标。</li>
        </ul>
        
        <h2>迭代能终止的前提</h2>
        
        <p>增量式迭代命令所使用的算法只保证在数据集的大小有界的情况下， 迭代才会停止， 换句话说， 如果被迭代数据集的大小不断地增长的话， 增量式迭代命令可能永远也无法完成一次完整迭代。</p>
        
        <p>从直觉上可以看出， 当一个数据集不断地变大时， 想要访问这个数据集中的所有元素就需要做越来越多的工作， 能否结束一个迭代取决于用户执行迭代的速度是否比数据集增长的速度更快。</p>
        
        <h2>返回值</h2>
        
        <p><a href="/commands/scan.html">SCAN</a>, <a href="/commands/sscan.html">SSCAN</a>, <a href="/commands/hscan.html">HSCAN</a> and <a href="/commands/zscan.html">ZSCAN</a> 命令都返回一个包含两个元素的 multi-bulk 回复： 回复的第一个元素是字符串表示的无符号 64 位整数（游标）， 回复的第二个元素是另一个 multi-bulk 回复， 包含了本次被迭代的元素。</p>
        
        <ul>
        <li><a href="/commands/scan">SCAN</a> 命令返回的每个元素都是一个key。</li>
        <li><a href="/commands/sscan">SSCAN</a> 命令返回的每个元素都是一个集合成员。</li>
        <li><a href="/commands/hscan">HSCAN</a> 命令返回的每个元素都是一个键值对，一个键值对由一个键和一个值组成。</li>
        <li><a href="/commands/zscan">ZSCAN</a>命令返回的每个元素都是一个有序集合元素，一个有序集合元素由一个成员（member）和一个分值（score）组成。</li>
        </ul>
        
        <h2>另外的例子</h2>
        
        <p>迭代hash中的键值对：</p>
        
        <pre><code>redis 127.0.0.1:6379&gt; hmset hash name Jack age 33&#x000A;OK&#x000A;redis 127.0.0.1:6379&gt; hscan hash 0&#x000A;1) &quot;0&quot;&#x000A;2) 1) &quot;name&quot;&#x000A;   2) &quot;Jack&quot;&#x000A;   3) &quot;age&quot;&#x000A;   4) &quot;33&quot;&#x000A;</code></pre>
      </article>
    </div>
    
    <script type='text/javascript'>startShow();</script>
    <div class='text' id='comments'>
      <div id='disqus_thread'></div>
      <script type='text/javascript'>
        //<![CDATA[
          var disqus_shortname = 'rediscn';
          
          // The following are highly recommended additional parameters. Remove the slashes in front to use.
          var disqus_identifier = 'command_'+curCommandObj.key;
          var disqus_url = curCommandObj.getdisqusUrl();
          
          /* * * DON'T EDIT BELOW THIS LINE * * */
          (function() {
            var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
              dsq.src = 'http://' + disqus_shortname + '.disqus.com/embed.js';
              (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
          })();
        //]]>
      </script>
      <a class='dsq-brlink' href='http://disqus.com'>
        Comments powered by
        <span class='logo-disqus'>
          Disqus
        </span>
      </a>
    </div>

    
    <script src='/js/foot.js'></script>
    
  </body>
</html>
